Function            popup_alloc - allocate memory for a popup menu

  Syntax              struct popup_header *popup_alloc(int left, int top,
                                     int right, int bottom, char *frame,
                                     char *title, int titlejustify, char
                                     *command[], int cmdkey[], char
                                     cmdflag[], int colframe, int
                                     coltitle, int colnorm, int
                                     colcmdkey, int colhilite, int
                                     coldisable, int coldishilite, int
                                     colnotopt, int defaultcommand,
                                     unsigned flags);

  Prototype in        menuhk.h

  Remarks             popup_alloc creates a popup menu with the following
                      information:

                      Coordinates of the frame of the popup menu are
                      (left,top) to (right,bottom), the border is made up
                      of the 9 or 11 chars in frame (0 to 8 or 10) as per
                      boxwindow(), with an optional title on the top edge
                      of the menu border, justified left, right or center
                      (see howard.h for more details).

                      The command array is a list of strings or text to
                      be displayed on the screen. popup_alloc knows how
                      many commands it needs by the size of the box, one
                      per line (i.e. coordinates (1,1) to (10,5) would
                      need 3 commands since there are 3 lines inside the
                      popup box).

                      Each command can have a hotkey associated with it,
                      denoted by the appropriate cmdkey[]. The 'hotkey'
                      is actually a one-touch key, instantly moving to
                      and selecting a choice. The cmdkey value is an
                      offset into the command string. For example, a
                      command "Edit" with a hotkey of the "E" would have
                      a cmdkey value of 0 (an offset from the beginning
                      of the command). A command without a hotkey has a
                      cmdkey value of -1.

                      Each command has an appropriate cmdflag field. A
                      command may be either:

                           ENABLED     - a valid choice
                           DISABLED    - displayed, but not selectable
                           NOTOPTION   - not a command (static text)

                      These are defined in menuhk.h. Other values may
                      cause unpredictable results.

                      The following colors are used:

                           colframe       - frame around menu
                           coltitle       - title (if any)
                           colnorm        - enabled commands
                           colcmdkey      - hotkey in command
                           colhilite      - currently hilited option
                           coldisable     - disabled options
                           coldishilite   - disabled and currently
                                            hilited
                           colnotopt      - static text (NOTOPTION)

                      defaultcommand is the command initially hilited. If
                      an invalid command is chosen (the command is static
                      text, or does not exist, etc.) the first valid
                      command is the default.

                      flags is a 2-byte bit field of flags

                           QEFxxxxH UDIRCEDW

                      where

                           Q = Quit after selection
                           E = ESC means quit
                           F = Free memory on quit
                           H = Hierarchial menu (not implemented yet)

                           U = call _idle_menu() after keyboard input
                           D = free time slices under DESQview
                           I = cmdkeys are case Independent
                           R = Restore cursor before returning
                           C = don't hide Cursor
                           E = Erase menu on free/cleanup
                           D = Disabled not hilitable
                           W = Wraparound

                      Briefly, Quit will restore the display to the state
                      it was in before the popup menu was called
                      (settextinfo(), etc.). With E, if ESC is pressed
                      the menu is removed, for any other selection no
                      cleanup is done (unless Q is specified). Free
                      memory on quit calls popup_free() after a selection
                      is made. Hierarchial menus are not implemented yet.
                      Keys are input via inkey(), inkeyc(), inkeydv() or
                      inkeycdv(), depending on case Independency and
                      freeeing time slices under DESQview. When
                      popup_get() is called, the cursor is hidden unless
                      C is given. The cursor is unhidden only if R is
                      given. E will cause the menu to be erased from the
                      screen if quitting. Disbaled commands are normally
                      selectable, unless D is on. Wraparound allows the
                      selecting hilite bar to wrap over the top and under
                      the bottom.

                      After input is polled, if the user defined function
                      flag is set (UDFIDLE) the function _idle_menu is
                      called. Currently, the definition of _idle_menu is:

                                int _idle_menu(void)

                      Possible uses for such a function is an onscreen
                      clock, printing, or some other background task. In
                      the future _idle_menu() will receive releveant
                      parameters. To define _idle_menu as the user
                      defined function int myfunction(void), try:

                           _idle_menu = (far *)myfunction;

                      The full definition for _idle_menu() is:

                           int (far *_idle_menu)(void);

                      You should declare myfunction() as type int, with
                      void parameters, and you should typecast the
                      function as a far pointer when you assign it to
                      _idle_menu.

  Return value        allocates and returns a pointer to a popup header
                      structure if the menu was successfully created,
                      otherwise returns NULL if an error occurred.
                      popuperrno will have the following values:

                           0    success
                           1    error, could not allocate popup header
                           2    error, could not allocate videosave
                           3    error, could not allocate menusave
                           5    error, could not allocate popup field
                           6    error, could not allocate command string
                           7    error, no menu item enabled (no commands)

  Note                The popup_header structure contains important
                      information about the menu, including pointers to
                      linked lists for the fields, saved video displays,
                      etc. I strongly advise that you don't even think of
                      modifying this information yourself. Let the
                      popup...() functions handle it for you. These
                      functions have been developed and used over a
                      period of several months, programs and conditions
                      which proves them to be virtually bug free. If you
                      really want to mess with them yourself, feel free.
                      But I certainly wouldn't want to attempt it.
                      Modifying these functions even with the source code
                      is a headache.

  See also            menuhk.h
                      isHiliteable(), menu_popup(), popup_free(),
                      popup_get(), popup_restore(), popup_setcurrent(),
                      pophilite(), popunlite()
                      popuperrno

  Example             see demopop.c